home *** CD-ROM | disk | FTP | other *** search
/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / C / PARFNCT.ZIP / PARSE.DOC < prev    next >
Encoding:
Text File  |  1991-10-18  |  9.0 KB  |  339 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                                 PARSE - Function
  21.  
  22.                                   Version 1.0
  23.  
  24.                              for TURBO C & BORLANDC
  25.  
  26.                             Reference Documentation
  27.  
  28.  
  29.                                Copyright (c) 1991
  30.  
  31.                                Jonathan L. Rubin
  32.                                   P.O. Box 548
  33.                                   Newtown, PA
  34.                                      18940
  35.  
  36.                               All Rights Reserved
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.                                  Table of Contents
  47.  
  48.  
  49.           Disclaimer .......................................... 1
  50.  
  51.  
  52.           Overview ............................................ 2
  53.  
  54.  
  55.           Header Files ........................................ 3
  56.  
  57.  
  58.           Function Call ....................................... 4
  59.  
  60.  
  61.           Supported Functions ................................. 5
  62.  
  63.  
  64.           Unknown Fields ...................................... 6
  65.  
  66.  
  67.           PTEST.C ............................................. 7
  68.  
  69.           DISCLAIMER
  70.  
  71.  
  72.           THE FUNCTIONS INCLUDED IN THIS PACKAGE ARE, TO THE BEST OF
  73.           MY KNOWLEDGE, ORIGINAL OR USE STANDARD ACCEPTED ALGORITHMS.
  74.           THIS SOFTWARE AND MATERIALS ARE SOLD (OR IN THE CASE OF
  75.           SHAREWARE, PROVIDED FOR TRIAL) "AS IS" WITHOUT WARRANTY OF
  76.           ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT
  77.           LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  78.           FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
  79.           QUALITY AND PERFORMANCE OF THIS PRODUCT AND FUNCTIONS ARE
  80.           WITH YOU.  JONATHAN RUBIN DOES NOT WARRANT THAT THE
  81.           FUNCTIONS CONTAINED IN THE PROVIDED CODE WILL MEET YOUR
  82.           REQUIREMENTS OR THAT THE OPERATION OF THE FUNCTIONS OR
  83.           PROGRAMS WILL BE UNINTERRUPTED OR ERROR FREE.
  84.  
  85.           OVERVIEW
  86.  
  87.  
  88.           The PARSE function provides numerical solutions to numerical
  89.           based equations.  For example if a program were to pass the
  90.           Parse function the following string:
  91.  
  92.                     100 * (5+2)
  93.  
  94.           The Parse function will return the value of 700 as a string;
  95.  
  96.           Example:   4+6/2
  97.                      will return 7 as a string.
  98.  
  99.           Example:   (100*(5+2))/2
  100.                      will return 350 as a string.
  101.  
  102.           Example:   (100*(5+2))/3
  103.                      will return 233.333333333333 as a string.
  104.  
  105.           Parse uses the following Operator Precedence when evaluating
  106.           an expression.
  107.  
  108.           Operator Type          Operators             Associativity
  109.           ----------------------------------------------------------
  110.           Operators              ()                    Left to Right
  111.           Multiplicative         */                    Left to Right
  112.           Additive               +-                    Left to Right
  113.  
  114.  
  115.           Parse has a number of built in math functions for example
  116.           when passed the following string.
  117.  
  118.                     abs(3-7)
  119.  
  120.           The Parse function will return the value of 4 as a string;
  121.  
  122.  
  123.           You may optionally place field names within a function for
  124.           example:
  125.  
  126.                     100 * (sold/return)
  127.  
  128.           Parse will call a function located in your code and will
  129.           pass you a string with the unknown fieldname upon which your
  130.           function will replace the value of the unknown field with a
  131.           numeric value.  In this case the your function would be
  132.           called twice, once with the string "sold" and again with the
  133.           string "return".  Parse will then carry out the computation
  134.           with the new values.
  135.  
  136.           USING PARSE
  137.  
  138.  
  139.           Header Files
  140.           ------------
  141.  
  142.           Be sure to include the header file PARSE.H in your source
  143.           code.
  144.  
  145.           Example when the PARSE.H file is in the working directory:
  146.  
  147.  
  148.                #include "parse.h"
  149.  
  150.           Example when the PARSE.H file is in the include directory:
  151.  
  152.  
  153.                #include <parse.h>
  154.  
  155.           Function Call
  156.           -------------
  157.  
  158.  
  159.           Parse(char *equation,char *result,int recursion);
  160.           The third argument must be a zero.
  161.  
  162.           The mathematical symbols are supported:
  163.  
  164.               () : Operators
  165.                + : Addition
  166.                - : Subtraction
  167.                * : Multiply
  168.                / : Divide
  169.  
  170.           Included with this is a sample application which accepts an
  171.           equation, as command line arguments, and prints the results.
  172.  
  173.           Example:
  174.           --------
  175.  
  176.           #include <stdio.h>
  177.           #include "parse.h"
  178.  
  179.           main()
  180.           {
  181.            char equation[25],result[25];
  182.            int  returncode;
  183.  
  184.            strcpy(equation,"25+(500/3)");
  185.  
  186.            if( (returncode = Parse(equation,result,0) < 0)
  187.               printf("Error occurred %s\n",equation);
  188.            else
  189.               printf("Result of %s is %s\n",equation,result);
  190.  
  191.            exit(0);
  192.           }
  193.  
  194.           ParseValue(char *field)
  195.           {
  196.           return(0);
  197.           }
  198.  
  199.           Notes:
  200.           ------
  201.  
  202.           You must include the function ParseValue in your code or
  203.           your program will not compile.  Further you must return a
  204.           value greater than 0 if the Parse function is to complete
  205.           successfully.  For further information on the function
  206.           ParseValue see section on unknown fields.
  207.  
  208.           Parse will return a value of < 0 if an error. Values of
  209.           return codes are defined in the PARSE.H file.
  210.  
  211.           Supported Functions
  212.           -------------------
  213.  
  214.  
  215.           Your equations may include the following functions which are
  216.           implemented as outlined in the Turbo C Library Manual.  For
  217.           complete information an each function please refer to that
  218.           manual.
  219.  
  220.                     abs()
  221.                     acos()
  222.                     asin()
  223.                     atan()
  224.                     ceil()
  225.                     cos()
  226.                     cosh()
  227.                     exp()
  228.                     fabs()
  229.                     floor()
  230.                     labs()
  231.                     log()
  232.                     log10()
  233.                     sin()
  234.                     sinh()
  235.                     sqrt()
  236.                     tan()
  237.                     tanh()
  238.  
  239.  
  240.           Example: For the equation:
  241.  
  242.                   acos(0.5)*2
  243.  
  244.               Parse will return 2.0943951023932
  245.  
  246.           Unknown fields
  247.           --------------
  248.  
  249.  
  250.           Parse will call the function ParseValue when it is unable to
  251.           resolve the values of a token.  This is extremely useful
  252.           when you whish to build a program which contains stored
  253.           field values which may be substituted in an mathematical
  254.           equation. For example you may be building a spreadsheet
  255.           program or other runtime package where the user might enter
  256.           the following type of equation.
  257.  
  258.  
  259.                     100*(price/cost)
  260.  
  261.  
  262.           Parse will call the ParseValue function twice during the
  263.           evaluation of the expression.  The first time the Function
  264.           will be called with a string value of 'price' and a second
  265.           time with the value of 'cost'. Note: the ' is only used to
  266.           delimit the field within this documentation and is not a
  267.           part of the passed string.
  268.  
  269.           If a field is unknown then the function should return a -3
  270.           negative value upon returning from the ParseValue function.
  271.           This is defined in the PARSE.H file as FIELDUNKNOWN.
  272.  
  273.           A simplistic example follows:
  274.  
  275.  
  276.           ParseValue(char *field)
  277.           {
  278.             if(strcmp(field,"ABC") == 0)
  279.                strcpy(field,"123")
  280.  
  281.             else  if(strcmp(field,"DEF") == 0)
  282.                strcpy(field,"456")
  283.  
  284.             else
  285.                return(FIELDUNKNOWN);
  286.  
  287.             return(0);
  288.  
  289.           }
  290.  
  291.           PTEST.C
  292.           -------
  293.  
  294.  
  295.           The following is the PTEST.C sample.  PTEST takes an
  296.           equation as part of the command line arguments and prints
  297.           the results.  A sample command line example is:
  298.  
  299.                    C:\TC\TEST> PTEST  25+3
  300.  
  301.  
  302.  
  303.           /*         PTEST.C     */
  304.  
  305.  
  306.           #include <stdlib.h>
  307.           #include "parse.h"
  308.  
  309.           main(int argc,char *argv[])
  310.           {
  311.           int i,rc;
  312.  
  313.           char equ[80];
  314.           char result[25];
  315.  
  316.           equ[0] = 0x0;
  317.  
  318.           for(i = 1; i <= argc ; i++)
  319.            {
  320.             strcat(equ,argv[i]);
  321.             strcat(equ," ");
  322.            }
  323.  
  324.           rc=Parse(equ,result,0);
  325.  
  326.           printf("rc=%d equation='%s' result=%s\n",rc,equ,result);
  327.  
  328.           return(0);
  329.  
  330.           }
  331.  
  332.  
  333.           ParseValue(char *field)
  334.           {
  335.  
  336.           return(0);
  337.           }
  338.  
  339.